Skip to content

dspack v0.3: governance blocks (intents, rules, examples) + surface schema v0.1#9

Merged
ryandmonk merged 4 commits into
mainfrom
spec/v0.3-governance
Jul 2, 2026
Merged

dspack v0.3: governance blocks (intents, rules, examples) + surface schema v0.1#9
ryandmonk merged 4 commits into
mainfrom
spec/v0.3-governance

Conversation

@ryandmonk

Copy link
Copy Markdown
Contributor

What this is

PR-1 of Milestone 1 (governed generation vertical slice). dspack v0.3 adds the machine-checkable governance blocks — intents, rules, examples — plus the companion dspack surface schema (v0.1), the protocol-neutral component tree that rules are evaluated against.

Strictly additive over v0.2: a valid v0.2 document with "dspack": "0.3" validates against the v0.3 schema (checked on every validate run via the stripped-document guarantee).

Contents

  • schema/dspack.v0.3.schema.json — textual extension of the v0.2 schema (everything inherited is structurally identical; verified by the generator's deep diff). Three rule types as a discriminated union: component-choice, required-composition, forbidden-composition. No expression language. Unknown rule types are schema-invalid; linters must fail loudly (exit 4), never skip.
  • schema/dspack.surface.v0_1.schema.json — the surface format: nested component tree in contract vocabulary + declared intent. An intermediate representation: never rendered, never transported, always compiled.
  • spec/dspack-v0.3.md — delta spec: normative per-type evaluation semantics, severity mapping (contract must|should → tool error|warn, findings carry both), gate definitions (S1 generic schema / S2 contract vocabulary / S3 governance), the three-layer formulation, and the deliberate expressiveness ceiling (§9: ordering, category-based rules, cardinality, tokens/layout — named v0.4 candidates).
  • spec/migration-v0.2-to-v0.3.md — guarantees + a worked dialog-for-destructive-actions anti-pattern → rule.destructive-requires-alertdialog conversion.
  • examples/shadcn-ui.dspack.json — upgraded to v0.3: destructive-action intent, three worked rules (one per type) shadowing governance already present as prose, and the compilable ex.delete-account-confirmation surface. Note: rule.button-no-interactive-descendants lists ["button", "input"] only — the contract defines neither select nor textarea, and rule references must resolve in the contract vocabulary; the fuller list applies to contracts that define those ids (per-review note, ADR-D1 records the category-based v0.4 candidate).
  • scripts/validate.mjs + fixtures/negative/ + CI — the repo's first machine gate: schema-compile, example validation incl. S1/S2 over examples[].surface, cross-reference consistency, back-compat check; ten negative fixtures spanning schema-, consistency-, S1-, and S2-level rejections, each of which must fail.

Acceptance (machine-verifiable)

npm ci && npm run validate                     # exit 0
npm run validate -- --fixtures negative        # exit 0 iff all 10 fixtures rejected

Both run in CI (.github/workflows/validate.yml).

Hand-review focus

The two schemas and the spec delta (spec/dspack-v0.3.md §5 evaluation semantics in particular) — these are the milestone's expensive-to-change surfaces. Everything else is gate-verified.

ADRs: 1 (typed rules), 2 (canonical surface), 3 (examples), 6 (intents), 11 (severity).

🤖 Generated with Claude Code

…rface schema v0.1

dspack v0.3 makes a subset of a design system's institutional knowledge
machine-checkable. Strictly additive over v0.2: a valid v0.2 document with
"dspack": "0.3" validates against the v0.3 schema.

- schema/dspack.v0.3.schema.json: v0.2 + three optional top-level blocks.
  Rules are typed structured predicates (component-choice,
  required-composition, forbidden-composition) — no expression language;
  unknown rule types are schema-invalid per version and must fail loudly
  in linters. Severity is RFC 2119 (must|should); tools map must→error,
  should→warn.
- schema/dspack.surface.v0_1.schema.json: the dspack surface — a
  protocol-neutral component tree in contract vocabulary, the evaluation
  target for rules (gates S1/S2/S3) and the payload of examples[].surface.
  An intermediate representation: never rendered, never transported,
  always compiled.
- spec/dspack-v0.3.md: delta spec with normative per-type evaluation
  semantics, the severity mapping, gate definitions, the three-layer
  formulation, and the deliberate expressiveness ceiling.
- spec/migration-v0.2-to-v0.3.md: guarantees + worked anti-pattern→rule
  conversion.
- examples/shadcn-ui.dspack.json: upgraded to v0.3 with the
  destructive-action intent, three worked rules shadowing existing
  anti-patterns/constraints, and a compilable delete-account example.
- scripts/validate.mjs + fixtures/negative/ + CI: schemas compile; examples
  validate (incl. S1/S2 over example surfaces, cross-reference consistency,
  and the stripped-document back-compat guarantee); ten negative fixtures
  must each be rejected.

Verify: npm ci && npm run validate && npm run validate -- --fixtures negative

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 2, 2026 15:56

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Introduces dspack v0.3 as an additive delta over v0.2 by defining machine-checkable governance blocks (intents, rules, examples) and a companion “dspack surface” schema used as the evaluation target for governance and as the embedded format for examples[].surface.

Changes:

  • Add v0.3 spec + migration guide, and update READMEs to point to the new draft.
  • Add new JSON Schemas: dspack.v0.3 (contract) and dspack.surface.v0_1 (surface IR).
  • Add a Node/Ajv validation harness with negative fixtures and CI workflow gating.

Reviewed changes

Copilot reviewed 21 out of 22 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
spec/README.md Updates spec index to include v0.3 + migration doc and clarifies draft status.
spec/migration-v0.2-to-v0.3.md Adds migration guidance and a worked anti-pattern → rule example.
spec/dspack-v0.3.md Adds the v0.3 delta spec defining intents/rules/examples, surface format, and S1/S2/S3 gates.
scripts/validate.mjs Adds validation harness for schema compilation, examples validation, back-compat, and governance consistency checks.
schema/README.md Updates schema index and documents the new validation harness usage.
schema/dspack.v0.3.schema.json Adds v0.3 JSON Schema including governance blocks and typed rule union.
schema/dspack.surface.v0_1.schema.json Adds generic surface schema (S1) for protocol-neutral component trees.
README.md Updates repository status and milestone list to include v0.3 draft and references.
package.json Adds Node-based validation script and Ajv devDependencies.
package-lock.json Locks Ajv + ajv-formats dependencies for validation harness.
fixtures/negative/rule-unregistered-intent.dspack.json Negative fixture: rule applies to unregistered intent.
fixtures/negative/rule-unknown-type.dspack.json Negative fixture: unknown rule type rejected by schema.
fixtures/negative/rule-unknown-example-ref.dspack.json Negative fixture: rule references missing example.
fixtures/negative/rule-unknown-component-ref.dspack.json Negative fixture: rule references missing component.
fixtures/negative/rule-missing-rationale.dspack.json Negative fixture: rule missing required rationale.
fixtures/negative/rule-component-choice-empty.dspack.json Negative fixture: component-choice rule missing require/forbid arms.
fixtures/negative/example-surface-out-of-vocabulary.dspack.json Negative fixture: example surface uses component not in contract vocabulary (S2).
fixtures/negative/example-surface-invalid.dspack.json Negative fixture: surface fails generic surface schema (S1).
fixtures/negative/example-surface-bad-enum.dspack.json Negative fixture: invalid enum prop value in surface (S2).
fixtures/negative/example-missing-intent.dspack.json Negative fixture: example entry missing required intent.
examples/shadcn-ui.dspack.json Upgrades example contract to v0.3 with intents/rules/examples and an embedded surface example.
.github/workflows/validate.yml Adds CI workflow to run positive and negative validation gates.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread schema/dspack.v0.3.schema.json Outdated
Comment thread schema/dspack.v0.3.schema.json Outdated
Comment thread scripts/validate.mjs
Comment thread scripts/validate.mjs
…interactive-descendants

Design grounds, independent of any demo: ADR-7's repair template is designed
to carry a linked example as a corrected reference; the other two rules link
one; a rule whose repair feedback cannot include its corrected reference is
a contract gap regardless of any demo. Deliberately NOT a new example — the
existing one is already in the destructive-action few-shot, so this edit
changes repair feedback only (generation context is byte-identical), making
the rerun a clean A/B on that single variable. A new example would enter
generation context and could suppress first-attempt violations — the line
between fixing the contract and rigging the demo.

Observed consequence (recorded at exactly this strength, evidence in
dspack-gen docs/evidence/2026-07-02-flagship-candidates/): across 11
pipeline runs, rules with a linked example repaired whenever they fired;
the unlinked rule never repaired.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ryandmonk

Copy link
Copy Markdown
Contributor Author

Re-review flag (one-line diff): the follow-up commit links the existing ex.delete-account-confirmation to rule.button-no-interactive-descendants — the only rule whose repair feedback previously carried no corrected reference (ADR-7 gap; design grounds and the deliberately-not-a-new-example reasoning in the commit message). Validate harness green (npm run validate + negative fixtures). Diff: https://github.com/aestheticfunction/dspack/pull/9/files — the "examples" line on the third rule.

… sub-component ids

Review fixes (Copilot on #9):
- Closed governance objects (intentEntry, exampleEntry, appliesTo, and the
  nested rule requirement/constraint objects) now carry
  patternProperties ^x-, so x-prefixed extension keys validate per the
  global v0.2 extensibility rule while non-x unknown keys stay rejected.
  Spec delta states the compliance explicitly.
- buildVocabulary() surfaces duplicate sub-component ids and
  checkGovernance() rejects them before any id-dependent check — S2 and
  rule resolution must never depend on object iteration order. Spec delta
  makes document-wide sub-component id uniqueness normative for contracts
  using governance blocks; new negative fixture covers it (11 total).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…e non-x rejection

- checkGovernance() returns early for v0.3 documents that use none of
  intents/rules/examples — the duplicate-sub-id rule is scoped exactly as
  spec §5 states it, preserving the strictly-additive guarantee for pure
  v0.2-shaped documents.
- fixtures/negative/intent-non-x-unknown-key.dspack.json: holds the other
  direction of the extensibility fix in CI — x-owner passes, unknownField
  is rejected (12 negative fixtures total).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ryandmonk ryandmonk merged commit a1649c3 into main Jul 2, 2026
1 check passed
@ryandmonk ryandmonk deleted the spec/v0.3-governance branch July 5, 2026 02:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants